<html>
<head>
	<title>METviewer Documentation</title>
	<link rel="stylesheet" type="text/css" href="mv_doc.css" />
	<link rel="shortcut icon" href="include/ral_icon.ico" type="image/x-icon"/>
</head>
<body>

<p class="loc" style="padding-top:10px">
<b>Location:</b> <a class="loc" href="index.html">Home</a> &#187; METviewer Web Service
</p><hr/>

<h2>METviewer Documentation - METviewer Web Service</h2>

<p>The METviewer web service is a web-server driven API that parses XML requests and returns
  results in an XML structure.  All calls are session-less meaning
that each individual call does not affect and is not affected by the results of any other call.  Also, a client does not have to establish a connection with
the server and all calls can be made atomically.</p>

<p>The web service can be accessed using the relative URL metviewer/servlet, for example <a target="_blank" href="http://www.dtcenter.org/met/metviewer/servlet">
http://www.dtcenter.org/met/metviewer/servlet</a>.  When the web service receives an HTTP GET request, it echoes the GET parameters and acts as a "ping"
mechanism to ensure that the system is online and working.  All API XML requests should be issued using an HMTL POST request with the XML request as the entire
body.  The XML response will indicate the type of request, and echo some information.</p>

<p>There are several different request types, each with a particular format of response.  The
  METviewer client calls the different API methods in a loose
ordering:</p>
<ol>
   <li class="inst">list available databases</li>
   <li class="inst">list forecast variables for user selected database</li>
   <li class="inst">list stats for user selected database and forecast variable</li>   
   <li class="inst">list values for user selected fixed fields</li>
   <li class="inst">repeat steps 2-4 as needed</li>
   <li class="inst">plot request for user selected database and plot information</li>      
</ol>


<h3>API Request/Response Formats</h3>

<p>The following sections each describe a web service API function in terms of the request/response XML structure.</p><br/>


<b style="padding-left:20px; color: #002866">List Databases:</b>
<p>List the METviewer databases that are available on the system for access through the web app.
  The returned
list reflects the contents of the mvservlet.properties file in the web app installation folder.</p>

<p>
<b>Request:</b><br/><br/>
&nbsp;&nbsp;<span class="code">&lt;request&gt;&lt;list_db/&gt;&lt;/request&gt;</span>
</p>

<p>
<b>Response:</b><br/><br/>
<span class="code">&nbsp;&nbsp;&lt;list_db&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">mv_gfs_nam</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">mv_hmt_2010</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">mv_hmt_2011</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">mv_hwt_2010</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">mv_met_ncep</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&lt;/list_db&gt;</span>
</p>

<br/><br/>


<b style="padding-left:20px; color: #002866">List Values:</b>
<p>The list_val request is used to conditionally list the distinct values in the stat_header table of the selected database.  The field
whose values to list is specified in the stat_field element.  There are two conditions that can be optionally included in the request:
a fcst_var/stat pair and a stat_header field name with a set of values.  At this point, it is worth noting that although the fields 
fcst_lead, fcst_valid_beg and fcst_lead_beg are not in the stat_header table of the database schema, they are considered stat_header
fields from the standpoint of the METviewer servlet and client.  The virtual fields inithour and
  validhour are considered stat_header
fields.</p>

<p>The id element is common to the list_val and list_stat API methods, and the value specified in the request is simply echoed back to 
the client in the response.  This feature helps the client determine which controls should be updated with the contents of the response.
</p>

<p>
<b>Request #1:</b> In this case, the request is for all distinct values of the stat_header field fcst_var, without any conditions.<br/><br/>
<span class="code">&nbsp;&nbsp;&lt;request&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;db_con&gt;</span><span class="term">mv_gfs_nam</span><span class="code">&lt;/db_con&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;list_val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;id&gt;</span><span class="term">0</span><span class="code">&lt;/id&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;stat_field&gt;</span><span class="term">FCST_VAR</span><span class="code">&lt;/stat_field&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;/list_val&gt;<br/>
&nbsp;&nbsp;&lt;/request&gt;</span>
</p>

<p>
<b>Response #1</b><br/><br/>
<span class="code">&nbsp;&nbsp;&lt;list_val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;id&gt;</span><span class="term">0</span><span class="code">&lt;/id&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">APCP_03</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">APCP_24</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&lt;/list_val&gt;</span>
</p><br/>


<p>
<b>Request #2:</b> This conditional request is for all distinct values of vx_mask for which the fcst_var is APCP_03 and the statistic
type is categorical (the statistic CSI can be found in the database table line_data_cts).  An additional stat_header field condition
stipulates that only vx_mask values whose fcst_lead is 120000 should be returned.<br/><br/>
<span class="code">&nbsp;&nbsp;&lt;request&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;db_con&gt;</span><span class="term">mv_gfs_nam</span><span class="code">&lt;/db_con&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;list_val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;id&gt;</span><span class="term">3</span><span class="code">&lt;/id&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;stat_field&gt;</span><span class="term">VX_MASK</span><span class="code">&lt;/stat_field&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;stat&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;fcst_var name="</span><span class="term">APCP_03</span><span class="code">"&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">CSI</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/fcst_var&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/stat&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;field name="</span><span class="term">OBTYPE</span><span class="code">"&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">MC_PCP</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/field&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;/list_val&gt;<br/>
&nbsp;&nbsp;&lt;/request&gt;</span>
</p>

<p>
<b>Response #2:</b> The response contains only values of vx_mask for which the criteria are satisfied.  This feature is useful to users
for narrowing the results of subsequent search requests.  Note that, for performance reasons, time criteria such as fcst_valid_beg, 
fcst_init_beg and fcst_lead does not affect the results of non-time based fields and vice versa.<br/><br/>
<span class="code">&nbsp;&nbsp;&lt;list_val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;id&gt;</span><span class="term">3</span><span class="code">&lt;/id&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">FULL</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">CONUS</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">EAST</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&lt;/list_val&gt;</span>
</p>

<br/><br/>


<b style="padding-left:20px; color: #002866">List Statistics:</b>
<p>The list_stat request builds a list of all statistics available in the METviewer database for
  the specified fcst_var.  It is primarily
used to construct the dep1 and dep2 portions of the plot request.  Conditional criteria is not supported in list_stat requests.</p>

<p>
<b>Request</b><br/><br/>
<span class="code">&nbsp;&nbsp;&lt;request&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;db_con&gt;</span><span class="term">mv_gfs_nam</span><span class="code">&lt;/db_con&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;list_stat&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;id&gt;</span><span class="term">0</span><span class="code">&lt;/id&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;stat_fcst_var&gt;</span><span class="term">APCP_03</span><span class="code">&lt;/stat_fcst_var&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;/list_stat&gt;<br/>
&nbsp;&nbsp;&lt;/request&gt;</span>
</p>

<p>
<b>Response</b> (abridged)<br/><br/>
<span class="code">&nbsp;&nbsp;&lt;list_stat&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;id&gt;</span><span class="term">0</span><span class="code">&lt;/id&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">ACC</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">BASER</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">CSI</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">FAR</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;val&gt;</span><span class="term">GSS</span><span class="code">&lt;/val&gt;<br/>
&nbsp;&nbsp;&lt;/list_stat&gt;</span>
</p><br/>

<br/><br/>


<b style="padding-left:20px; color: #002866">Generate Plot:</b>
<p>Once a user has provided all the information for a complete plot specification, the plot request handles the parsing of the plot specification
and generation of the plot.  If a plot is successfully create from the plot specification, the location of the plot image is included in the
response.  If any error or warning information was captured from R during the process, it will be included in the r_error element.</p>

<p>
<b>Request</b><br/><br/>
<span class="code">&nbsp;&nbsp;&lt;request&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;db_con&gt;</span><span class="term">mv_gfs_nam</span><span class="code">&lt;/db_con&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;plot&gt;<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span>(see body of <a href="plot.html">plot element</a>)<span class="code"><br/>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;/plot&gt;<br/>
&nbsp;&nbsp;&lt;/request&gt;</span>
</p>

<p>
<b>Response</b><br/><br/>
<span class="code">&nbsp;&nbsp;&lt;plot&gt;</span><span class="term">plot_00155_20111019_122758</span><span class="code">&lt;/plot&gt;<br/>
&nbsp;&nbsp;&lt;r_error&gt;</span><span class="term">NAs produced by integer overflow</span><span class="code">&lt;/r_error&gt;</span>
</p><br/>


<b style="padding-left:20px; color: #002866">Open app with predefine database:</b>
<p>Use this url to open METviewer main page with predefine database:</p>
<span class="code">&nbsp;&nbsp;&nbsp;&nbsp;&lt;http://www.dtcenter.org/met/metviewer/metviewer1.jsp?db=name_of_database</span>

<br/><br/>

